home *** CD-ROM | disk | FTP | other *** search
/ Developer CD Series 1996 April: Mac OS SDK / Dev.CD Apr 96 SDK / Dev.CD Apr 96 SDK1.toast / Development Kits (Disc 1) / OpenDoc / Documentation / Tech Notes & Articles / Recipes / Iterators < prev    next >
Encoding:
Text File  |  1995-11-07  |  2.6 KB  |  95 lines  |  [TEXT/ttxt]
  1. OpenDoc™ Recipes
  2.  
  3. Iterators
  4. By The OpenDoc Design Team
  5. November, 1995
  6.  
  7.  
  8. © 1993-1995  Apple Computer, Inc. All Rights Reserved.
  9. Apple, the Apple logo, and Macintosh are registered trademarks of Apple Computer, Inc.
  10. Mac and OpenDoc are trademarks of Apple Computer, Inc. 
  11.  
  12.  
  13. Introduction
  14.  
  15. The OpenDoc interfaces used by part developers include several iterators:
  16.  
  17.     ODObjectIterator (NameSpace)
  18.     ODValueIterator (Name Space)
  19.     ODFacetIterator
  20.     ODFrameFacetIterator
  21.     ODDragItemIterator
  22.     ODLinkIterator
  23.     ODLinkSourceIterator
  24.     ODPlatformTypeListIterator
  25.     ODTypeListIterator
  26.     ODFocusSetIterator
  27.     ODWindowIterator
  28.  
  29. Part developers must also provide one iterator themselves, a subclass of:
  30.  
  31.     ODEmbeddedFramesIterator
  32.  
  33. Developers of non-exclusive focus modules must also provide a subclass of: 
  34.  
  35.     ODFocusOwnerIterator
  36.  
  37. Interfaces
  38.  
  39. All of these iterators have at least the following three methods:
  40.  
  41.     First()    - begins the iteration and returns the first element
  42.     Next()    - returns the next element
  43.     IsNotComplete() - returns true if there are more elements
  44.  
  45. Some of the iterators also have Last() and Previous() methods.
  46. Most iterators return values as the result of the First and Next methods
  47.  
  48. Usage
  49.  
  50. Iterators can be used in the following ways:
  51.  
  52.     ODFrameFacetIterator* iter = frame->CreateFacetIterator(ev);
  53.     for (ODFacet* facet = iter->First(ev); iter->IsNotComplete(ev);
  54.                 facet = iter->Next(ev))
  55.     {
  56.         
  57.     }
  58.  
  59. or the equivalent:
  60.  
  61.     ODFrameFacetIterator* iter = frame->CreateFacetIterator(ev);
  62.     ODFacet* facet = iter->First()
  63.     while (iter->IsNotComplete())
  64.     {
  65.         …
  66.          facet = iter->Next(ev);
  67.     }
  68.  
  69. or, if there is a well-defined NULL value for the elements:
  70.  
  71.     ODFrameFacetIterator* iter = frame->CreateFacetIterator(ev);
  72.     while ((facet = iter->Next(ev)) != kODNULL)
  73.     {
  74.     }
  75.  
  76.  
  77. Rules
  78.  
  79. • First() means both "start iteration" and "give me an item"
  80. • Next() means "give me the next item"
  81. • IsNotComplete() returns true if there are more items.
  82.  
  83. • If Next() is called before First(), it means First().
  84. • IsNotComplete() will throw an error (kODErrIteratorNotInitialized) if neither First() nor Next() has  been called.
  85.  
  86. • If an iterator is bidirectional, the direction is an invariant. Once the iteration has begun, you can't change directions.
  87. • For an empty collection, First() and Next() return the NULL value if there is one. IsNotComplete() returns kODFalse.
  88.  
  89. • If IsNotComplete() returns kODTrue, the last item obtained is valid.
  90. • If IsNotComplete() returns kODFalse (at the end of the iteration), Next() will return the NULL value, if there is one.
  91.  
  92. • If the underlying collection is modified while an iteration is in progress, the iterator methods will throw an exception (kODErrIteratorOutOfSync).
  93.  
  94.  
  95.